docs(adr): reconcile zsh-lint analyzer architecture#456
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR reconciles ADR 0011 (“zsh-lint Semantic Analyzer Architecture”) with the analyzer architecture currently shipped in z-shell/zsh-lint, updating the decision text to reflect the implemented conditional indexing + evaluation + suppression/finalization pipeline while keeping the ADR in PROPOSED status.
Changes:
- Rewrites the ADR’s context/decision to describe the conditional scope-index pass, rule evaluation, and suppression/finalization as three durable phases.
- Updates the documented rule/context interfaces and emphasizes external “product contracts” (IDs, suppression, output) via links rather than duplicating details.
- Replaces outdated consequences/alternatives claims (unconditional two-pass, accuracy/perf assertions) with bounded costs/limits and clearer alternatives.
Copilot review: the interface pairing implied a scope-aware rule must also implement Rule but never said so, leaving room to misread ScopeAwareRule as independently registrable.
Copilot review: the shipped module is mvdan.cc/sh/v3, so the syntax package's canonical import path is mvdan.cc/sh/v3/syntax, not mvdan/sh/syntax. Verified against zsh-lint's go.mod.
Per the decision packet in #455 (comment 5013562757), decider ss-o, 2026-07-25: 11A (retain the opt-in ScopeAwareRule extension point as shipped, no content change needed) / T1 (rename the heading to 'zsh-lint Conditional Semantic Analysis Pipeline', filename kept stable to avoid link churn) / D1 (revise in place and accept rather than supersede). Removed the now-resolved 'Decision review' section and added the Deciders field this ADR's template was missing.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
z-shell/zsh-lintWhy
ADR 0011 had drifted from the shipped Go analyzer: it described unconditional indexing, stale interfaces, unsupported accuracy claims, and an unmeasured performance claim. This documentation-only change records the implemented architectural boundary without changing analyzer behavior or copying transient implementation inventory.
Tracks #455 and ZSH-23.
Maintainer disposition (2026-07-25)
Decider ss-o, replying to the decision packet in #455 comment 5013562757 with:
ScopeAwareRuleextension point as shipped; no content change needed beyond acceptance.0011-zsh-lint-semantic-analyzer-architecture.md) to avoid link churn.Status is now
ACCEPTED, Decidersss-o, dated 2026-07-25. This resolves the "Maintainer decision requested" section below and supersedes the original "keep the decisionPROPOSED" line in Summary above.Maintainer decision requested
Please decide whether to retain the optional scope-index extension point and whether to accept, amend, supersede, or reject the reconciled ADR. Acceptance still requires a named decider and date.
Verification
First pass (initial reconciliation commit):
Checked 1 file,No issuesgit diff --check 8ee04162..71286af3zsh-lintsource/contract paths resolved at audited commite714dc3eSecond pass (Copilot review responses and the 2026-07-25 disposition commit):
mvdan/sh/syntax->mvdan.cc/sh/v3/syntax), verified againstzsh-lint'sgo.modScopeAwareRulecomposes withRulerather than replacing it